home *** CD-ROM | disk | FTP | other *** search
/ ETO Development Tools 1 / ETO Development Tools 1.iso / Essentials / Developer Essentials Jul 90 / Technical Docs / Apple II Technical Notes / Technical Notes (Text) / IIGS / TN.IIGS.053 < prev    next >
Encoding:
Text File  |  1989-11-10  |  12.5 KB  |  254 lines  |  [TEXT/pdos]
  1. Apple II
  2. Technical Notes
  3. _____________________________________________________________________________
  4.                                                   Developer Technical Support
  5. Apple IIGS
  6. #53:    Desk Accessories and Tools
  7.  
  8. Revised by:    Dave Lyons                                       November 1989
  9. Written by:    Matt Deatherage & Jim Mensch                        March 1989
  10.  
  11. This Technical Note describes new guidelines for developers to help 
  12. applications and desk accessories live together in the same system at the same 
  13. time.
  14. Changes since March 1989:  Added additional discussion and minor 
  15. revisions; corrected tool set numbers for Event Manager and QuickDraw 
  16. Auxiliary.
  17. _____________________________________________________________________________
  18.  
  19.  
  20. Desk accessories vary widely in complexity.  Classic Desk Accessories (CDAs) 
  21. range from simple status-reporting programs to complete system-level debugging 
  22. utilities, and similarly, New Desk Accessories (NDAs) range from static 
  23. windows with pictures to nearly full-fledged applications.
  24.  
  25. This Note presents some new guidelines aimed at helping developers of both 
  26. applications and desk accessories to get their products to work together now 
  27. and in the future.
  28.  
  29.  
  30. Tool Sets
  31.  
  32. The greatest conflict between applications and desk accessories, especially 
  33. NDAs, is the use of system tool sets.  The Apple IIGS Toolbox Reference, 
  34. Volume 1, defines which tools are available for use by NDAs.  The Desk Manager 
  35. requires starting the following tool sets before calling FixAppleMenu (which 
  36. installs the names of the NDAs in the Apple menu):
  37.  
  38.     Tool Locator (#1)
  39.     Memory Manager (#2)
  40.     Miscellaneous Tools (#3)
  41.     QuickDraw II (#4)
  42.     Event Manager (#6)
  43.     Window Manager (#14)
  44.     Menu Manager (#15)
  45.     Control Manager (#16)
  46.     LineEdit (#20)
  47.     Dialog Manager (#21)
  48.     Scrap Manager (#22)
  49.  
  50. Since the Desk Manager requires starting these tools before calling 
  51. FixAppleMenu, NDAs may assume that these tools are all present and running, so 
  52. they do not need to check for their presence.  In addition to these 
  53. requirements by the Desk Manager, Apple strongly recommends that all 
  54. applications start the following tools:
  55.  
  56.     QuickDraw Auxiliary (#18)
  57.     Font Manager (#27)
  58.  
  59. These two additional tools are so widely used by desk accessories that they 
  60. should be present.  NDAs may not assume their presence, but it is reasonable 
  61. to write an NDA that checks for them, with the assumption that they will 
  62. usually turn out to be available.
  63.  
  64.  
  65. The Golden NDA Guideline
  66.  
  67. Developers who wish to maintain maximum compatibility between their NDAs and 
  68. applications, both now and in the future, should consider every environment 
  69. change they make with the following Golden NDA Guideline firmly in mind:
  70.  
  71.     "I, an NDA, pledge not to alter the environment of the application 
  72.     under which I run, and I will behave in such a way that the 
  73.     application runs the same whether I am present or not."
  74.  
  75. Of course, this guideline does not include such necessary tasks as the normal 
  76. (and reasonable) allocation of memory.  An application must be prepared to 
  77. handle a memory allocation call by a desk accessory, operating system, or even 
  78. a tool at unexpected times.  The guideline does, however, mean that your desk 
  79. accessory cannot change the operating environment, including such things as 
  80. the presence of tools and operating system parameters.  The following sections 
  81. detail some of the most important ways to follow the Golden NDA Guideline.
  82.  
  83.  
  84. Desk Accessory Guidelines
  85.  
  86. Extra Tools
  87.  
  88. o    If an NDA needs to use a tool which is not guaranteed to be available 
  89.      (e.g., Standard File), it should check to see if the tool is already 
  90.      running.  If it is not running, the NDA must use LoadOneTool to load it, 
  91.      then it must start the tool before using it.  When finished with the 
  92.      tool, the NDA must shut it down and unload it with UnloadOneTool.  (A 
  93.      tool is already running if its xxxStatus function returns TRUE and no 
  94.      error.)
  95.  
  96. o    If an NDA needs to start up a tool and keep it started while letting 
  97.      the application continue to run, things quickly get complicated.
  98.  
  99.      The Golden NDA Guideline shows why this is true.  If your NDA starts a 
  100.      tool which the application is going to use but has not yet started 
  101.      (i.e., the Font Manager), and your NDA does not shut it down before the 
  102.      application regains control, the application will (in this example) get 
  103.      error $1B01 (Font Manager Already Started) when it makes an FMStartUp 
  104.      call.  Many applications stop gracelessly on getting a tool startup 
  105.      error.
  106.  
  107.      In this case, the Golden NDA Guideline means that an application must 
  108.      not be forced to check the status of a tool which it has not started.  
  109.      Applications are not required to do so, and most of them do not.
  110.  
  111.      A previous version of this Note advised NDAs to start up and shut down 
  112.      tools when their windows were activated and deactivated.  This approach 
  113.      isn't strong enough to solve all the problems, since the application may 
  114.      decide to start up tools based on menu items (which can still be 
  115.      selected while an NDA window is in front).
  116.  
  117.      The only completely safe way to use a tool that isn't already running is 
  118.      to start it, use it, and shut it back down without ever returning 
  119.      control to the application while the tool set is started.
  120.  
  121.      Starting QuickDraw Auxiliary when the application has not started it can 
  122.      get you into a lot of trouble:  an application that correctly implements 
  123.      320/640 mode switching will call QDShutDown and QDStartUp.  QuickDraw 
  124.      Auxiliary depends heavily on QuickDraw, and restarting QuickDraw while 
  125.      QuickDraw Auxiliary is active will easily toast you.
  126.  
  127. o    If your NDA allocates bank-zero work area space for tool sets, be sure 
  128.      to dispose of it at DeskShutDown time (when your DAInit entry is called 
  129.      for shutdown).  If you don't, the system will die with error $0201 when 
  130.      trying to launch a ProDOS 8 application, since GS/OS needs all of banks 
  131.      0 and 1 to start ProDOS 8.
  132.  
  133. o    Sound tools provide the one exception to the rule of freely using a tool 
  134.      which is already started.  Refer to the section on System Parameters for 
  135.      more details on using sound tools.
  136.  
  137. o    NDAs must not shut down tools which they have not started.
  138.  
  139. o    CDAs are nearly always modal, but by using the HeartBeat interrupt queue 
  140.      or other mechanisms, they can get control when the user is no longer 
  141.      "in" the CDA.  The list of guaranteed tools for NDAs does not apply to 
  142.      CDAs, and CDAs must be prepared to deal with the ProDOS 8 environment as 
  143.      well as GS/OS.
  144.  
  145. System Parameters
  146.  
  147. o    A desk accessory (CDA or NDA) must not change a system resource or 
  148.      parameter which cannot be restored to its original condition.  A 
  149.      trivial, but illustrative, example of this is the number of times a 
  150.      pull-down menu item blinks when you select it.  This number (three by 
  151.      default) may be changed with the SetMItemBlink call, but there is no 
  152.      corresponding GetMItemBlink call, so you cannot retrieve the current 
  153.      value.  Therefore, a desk accessory must not change this parameter, and 
  154.      the same rule applies to any other system parameter for which you cannot 
  155.      determine a current value.
  156.  
  157. o    This idea extends to calling tool startup functions.  Even though a 
  158.      tool's startup function may not return an error when the tool is already 
  159.      active, the startup function could reset certain parameters upon which 
  160.      the application depends.  An example of this is TLStartUp for the Tool 
  161.      Locator.  A seemingly innocuous call, TLStartUp actually disconnects any 
  162.      user tool sets present, which, in this case, would most likely have been 
  163.      installed by the current application.  CDAs and NDAs must never call 
  164.      TLStartUp or TLShutDown.
  165.  
  166.      A desk accessory should not call any tool's startup function if the tool 
  167.      is already active.  The one exception to this rule is the Memory 
  168.      Manager's MMStartUp call, which a desk accessory may make to obtain its 
  169.      User ID.  Think of MMStartUp as a "GetMyID" call.
  170.  
  171. o    A desk accessory cannot use any of the sound tools if they are already 
  172.      started.  This is contrary to the rule for other tool sets, but it is 
  173.      required because there is no memory management of the sound RAM (or "DOC 
  174.      RAM").  If the Sound Tools (#8) are started, the application has 
  175.      exclusive control of the 64K DOC RAM used to play sounds.  Anything your 
  176.      desk accessory might put there could overwrite information the 
  177.      application needs.
  178.  
  179.      Saving and restoring DOC RAM around desk accessory usage is not 
  180.      sufficient.  Many of the sound functions are interrupt driven, altering 
  181.      the contents of DOC RAM only during sound interrupts, so your desk 
  182.      accessory might attempt to replace parts of DOC RAM which are being 
  183.      played.  Since there is no memory management of DOC RAM, desk 
  184.      accessories must avoid the sound functions of the IIGS if the 
  185.      application is already using them.
  186.  
  187. o    A desk accessory must not install user tool sets, because there is no 
  188.      arbitration of user tool set numbers.  User tool sets are the sole 
  189.      property of the current application.
  190.  
  191.  
  192. Application Guidelines
  193.  
  194. To coexist peacefully with desk accessories, particularly NDAs, applications 
  195. generally need to follow the guidelines listed in the Desk Manager chapter of 
  196. the Apple IIGS Toolbox Reference, Volume 1.  However, those applications which 
  197. wish to ensure maximum compatibility now and in the future will also want to 
  198. adhere to the following:
  199.  
  200. o    Don't just start the Scrap Manager--use it.  Many desk accessories 
  201.      support cutting and pasting to exchange text and pictures with your 
  202.      application, but they can do it only if you use the Scrap Manager.  If 
  203.      you have a need for your own private scrap internally, you should still 
  204.      also use the Scrap Manager to exchange text and pictures with other 
  205.      applications and DAs.
  206.  
  207. o    Start tools at the beginning of your application and leave them started.  
  208.      Every time you call SystemTask or TaskMaster, a desk accessory may get 
  209.      control of the system, and if your application has shut down a tool that 
  210.      a desk accessory found running and is using, the DA might not be able to 
  211.      complete an operation.
  212.  
  213.      For maximum compatibility, do not shut down any tools which were ever 
  214.      active when you called SystemTask or TaskMaster.  You can start more 
  215.      tools, but do not shut down those which are already active.  If you 
  216.      intend to start a tool and not keep it started, use it then shut it down 
  217.      immediately, being sure not to call SystemTask or TaskMaster during that 
  218.      time.
  219.  
  220. o    Applications should not call CloseAllNDAs while shutting down.  Since 
  221.      DeskShutDown closes all open NDAs anyway, it's not necessary.  By not 
  222.      calling CloseAllNDAs, you allow the system or NDAs to tell the 
  223.      difference between just cleaning up and really wanting to close all 
  224.      the NDAs.
  225.  
  226. o    Applications should never make a Close call with reference number zero 
  227.      at file level zero.  (If you need to use Close with reference number 
  228.      zero, use GetLevel and SetLevel to avoid closing files you did not 
  229.      open.)
  230.  
  231. o    An application with some memory to spare can save NDAs time by providing 
  232.      them the additional tools which they are most likely to use.  If a desk 
  233.      accessory needs the List Manager and your application starts it, the 
  234.      desk accessory will run faster since it can avoid loading and starting 
  235.      the tool every time it gets control.
  236.  
  237.  
  238.      The most common tools which desk accessories require besides those 
  239.      available in the standard Desk Manager set are QuickDraw Auxiliary 
  240.      (#18), the Print Manager (#19), Standard File (#23), the Font Manager 
  241.      (#27), and the List Manager (#28).  QuickDraw Auxiliary and the Font 
  242.      Manager are especially important--not only do they work well together, 
  243.      but they are also widely used.  In addition, FMStartUp can take a long 
  244.      time, and waiting for it every time you activate an NDA window can be 
  245.      really frustrating.  Many desk accessories also use the Print Manager, 
  246.      the List Manager, and Standard File, and if they are always available, 
  247.      desk accessories will work more smoothly with your application.
  248.  
  249.  
  250. Further Reference:
  251. _____________________________________________________________________________
  252.     o    Apple IIGS Toolbox Reference, Volume 1
  253.     o    Programmer's Introduction to the Apple IIGS
  254.